<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Strict//EN">
<html>

<head>
<meta http-equiv="Content-Language" content="en-us">
<title>simRegisterScriptCallbackFunction</title>
<link rel="stylesheet" type="text/css" href="../../style.css">
</head>

<body>

<div align="center">
<table class=allEncompassingTable >
 <tr>
  <td >
<p><a href="../../index.html" TARGET="_top"><img src="../images/homeImg.png"></a></p>

<h1>Regular API function</h1>
<h3 class=subsectionBar><a name="simRegisterScriptCallbackFunction" id="simRegisterScriptCallbackFunction"></a>simRegisterScriptCallbackFunction</h3>
<table class=apiTable>
<tr class=apiTableTr> 
<td class=apiTableLeftDescr>
Description 
</td> 
<td class=apiTableRightDescr>Registers a custom script function, that calls back a c/c++ function. This function is useful for plugins that wish to provide their own or customized script functions. See also <a href="simRegisterScriptVariable.htm">simRegisterScriptVariable</a>.
<br><br>
<div>Data exchange between a script and the plugin happens via a <a href="../apiFunctions.htm#stacks">stack</a>. Reading and writing arguments from/to the stack gives you a maximum of flexibility, and you wil be able to exchange also complex data structures. But it can also be tedious, if your data structures are anyway relatively simple. In that case you can use the helper classes <em>CScriptFunctionData</em> and <em>CScriptFunctionDataItem</em> located in <em>programming/common</em> and <em>programming/include</em>: they will greatly simplify the task.</div>
<br>
<div>Use following 4 functions in the helper class: <em>readDataFromStack</em>, <em>getInDataPtr</em>, <em>pushOutData</em> and <em>writeDataToStack</em>.</div>
</td>
</tr> 
<tr class=apiTableTr> 
<td class=apiTableLeftCSyn>
C synopsis
</td> 
<td class=apiTableRightCSyn>simInt simRegisterScriptCallbackFunction(const simChar* funcNameAtPluginName,const simChar* callTips,simVoid(*callBack)(struct SScriptCallBack* cb))<br></td> 
</tr> 
<tr class=apiTableTr> 
<td class=apiTableLeftCParam>C parameters</td> 
<td class=apiTableRightCParam>
<div><strong>functNameAtPluginName</strong>: name of the function, combined with the plugin name: functionName@pluginName. Avoid using too simple function names, otherwise they might clash with other plugins. Also, always use the <em>simXX.</em> prefix (e.g. <em>simMyPlugin.myCustomFunction</em>) for the function name. The plugin name should be the exact same name used while loading the plugin via <a href="simLoadModule.htm">simLoadModule</a> (if the plugin name is <em>simExtMyPlugin.dll</em>, this should be <em>MyPlugin</em>).<br>
</div>
<div><strong>callTips</strong>: call tips: string (or several strings separated by '@') that indicates the input/output argument type/size. Call tips appear in the script editor when the function was typed followed by &quot;(&quot;. callTips Can be nullptr, in which case no call tips will be displayed, nor syntax highlighting used.<br>
</div>
<div><strong>callback</strong>: callback address that is called when the &quot;functName&quot; function is called from Lua. Can be nullptr, in which case the command will only register the function for call tips and syntax highlighting. See further down for a simple way to call above function, using a helper class. The callback's first argument is a SScriptCallBack structure that holds:<br>
</div>
<br>
<div><strong>simInt objectID</strong>: handle of the object that the calling script is attached to, or -1 if the calling script is not a child script<br>
</div>
<div><strong>simInt scriptID</strong>: handle of the calling script<br>
</div>
<div><strong>simInt stackID</strong>: a <a href="simCreateStack.htm">stack handle</a>. The stack is used to read arguments from the script, and to return data to the script.  See also the <a href="../apiFunctions.htm#stacks">available stack functions</a>.<br>
</div>
<br>

</td> 
</tr> 
<tr class=apiTableTr> 
<td class=apiTableLeftCRet>
C return value
</td> 
<td class=apiTableRightCRet>
<div>1 if function was registered, 0 if function was replaced (when that function name already existed), -1 in case of an error<br>
</div>
</td> 
</tr> 
<tr class=apiTableTr> 
<td class=apiTableLeftLSyn>
Lua synopsis
</td> 
<td class=apiTableRightLSyn>see <a href="simRegisterScriptFunction.htm">sim.registerScriptFunction</a> instead.</td> 
</tr> 
<tr class=apiTableTr> 
<td class=apiTableLeftLParam>Lua parameters</td> 
<td class=apiTableRightLParam>
<div>-</div>
<div></div></td> 
</tr> 
<tr class=apiTableTr> 
<td class=apiTableLeftLRet>
Lua return values
</td> 
<td class=apiTableRightLRet>
<div>-</div>
<div></div></td> 
</tr> 
</table> 


<br>
</td>
</tr>
</table>
</div>
</body>
</html>
